====================
Global Configuration
====================

The global configuration is responsible for configuring many different
aspects of the autotest programs. The client, server, scheduler, some
portions of the frontend as well as other stand alone scripts require
this file to get specific information about your setup. Below is a list
of sections and in each section the options available in the
configuration are described.

If you are making a stand alone checkout of the autotest client, it will
warn you that you might want to create a default config file. If you
want to do so, create a global_config.ini file inside the client
directory with the documented keys on this page, it will look something
like this:

::

    [CLIENT]
    drop_caches: True
    drop_caches_between_iterations: True

For the other autotest programs, it's necessary that you have
global_config.ini set on a proper location.


CLIENT
------

This section describes the global config [CLIENT] section.

+-------------------------------------+---------------------------------------------------------------------------------------------------------------+
| **Key**                             | **Description**                                                                                               |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------+
| drop_caches                         | If the autotest client will drop the memory cache for the client machine between test executions              |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------+
| drop_caches_between_iterations      | If the autotest client will drop the memory cache for the client machine between test iterations executions   |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------+
| output_dir                          | Specify an alternate location to store the test results.                                                      |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------+

COMMON
------

This section describes the global config [COMMON] section.

+-------------------------------------+---------------------------------------------------------------------------------------------------------------+
| **Key**                             | **Description**                                                                                               |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------+
| autotest_top_path                   | The path for the toplevel autotest directory, defaults to /usr/local/autotest, might vary among distributors. |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------+

AUTOTEST_WEB
-------------

Parameters for configuring the frontend and scheduler database
connections

+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Key**                         | **Description**                                                                                                                                                                                                                                                                                            |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| host                            | The host name where the database is located                                                                                                                                                                                                                                                                |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| database                        | The name of the database                                                                                                                                                                                                                                                                                   |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| db_type                         | The type of database running (mysql, sqlite)                                                                                                                                                                                                                                                               |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| user                            | Username to connect to the database                                                                                                                                                                                                                                                                        |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| password                        | Username to connect to the database                                                                                                                                                                                                                                                                        |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| job_timeout_default             | Default timeout (in hours) for new jobs. If the job gets schedule but it doesn't get to run, it'll be aborted without it running at all if this timeout is reached.                                                                                                                                        |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| job_max_runtime_hrs_default     | Default timeout (in hours) for running jobs. If job gets to run, but it doesn't finish during this timeout, it'll be aborted.                                                                                                                                                                              |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| base_url                        | URL to your Autotest server's AFE interface. You only need this option if the URL is something other than http://$hostname/afe/, where $hostname is the "hostname" value from the SERVER section.                                                                                                          |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| template_debug_mode             | Whether to enable django template debug mode. If this is set to True, all django errors will be wrapped in a nice debug page with detailed environment and stack trace info. Turned off by default.                                                                                                        |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| sql_debug_mode                  | Whether to enable django SQL debug mode. If this is set to True, all queries performed by the Object Relational Mapper subsystem will be printed, which means the scheduler logs will contains all the queries executed. This is too much verbosity for 'production' systems, hence turned off by default. |
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Retry configuration
~~~~~~~~~~~~~~~~~~~

The db.py API for connecting to the TKO database includes support for
automatically reconnecting and retrying queries when they fail due to
OperationalErrors (assuming this is possible, i.e. when autocommit is in
use).

+---------------------+----------------------------------------------------------------------------------------------------+
| **Key**             | **Description**                                                                                    |
+---------------------+----------------------------------------------------------------------------------------------------+
| query_timeout       | Maximum number of seconds to wait before no giving up and no longer retrying                       |
+---------------------+----------------------------------------------------------------------------------------------------+
| min_retry_delay     | The minimum number of seconds to wait after an OperationalError before reconnecting and retrying   |
+---------------------+----------------------------------------------------------------------------------------------------+
| max_retry_delay     | The maximum number of seconds to wait after an OperationalError before reconnecting and retrying   |
+---------------------+----------------------------------------------------------------------------------------------------+

Graph configuration
~~~~~~~~~~~~~~~~~~~

Configuration parameters for the TKO graphing interface

+--------------------------------------------+------------------------------------------------------------------------------+
| **Key**                                    | **Description**                                                              |
+--------------------------------------------+------------------------------------------------------------------------------+
| graph_cache_creation_timeout_minutes       | How frequently cached images for embedded graphing queries will be updated   |
+--------------------------------------------+------------------------------------------------------------------------------+


AUTOSERV
--------

+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Key**                       | **Description**                                                                                                                                                                                                    |
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| client_autodir_paths          | A comma-delimited list of paths where autoserv will attempt to install clients onto test machines                                                                                                                  |
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ssh_engine                    |  Autotest has 2 implementations of SSH based hosts, the default (raw_ssh), and another one based on the python SSH library paramiko (paramiko). You can change the default 'raw_ssh' to 'paramiko' if you want to. |
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| enable_master_ssh             |  Enable OpenSSH connection sharing. Only useful if ssh_engine is 'raw_ssh'                                                                                                                                         |
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| require_atfork_module         | Fix problems originated from logging + threading inside autotest. Specially useful when ssh_engine is 'paramiko'                                                                                                   |
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| use_sshagent_with_paramiko    | Set to False to disable ssh-agent usage with paramiko                                                                                                                                                              |
+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+


SERVER
------

+------------+------------------------------------------------------------------+
| **Key**    | **Description**                                                  |
+------------+------------------------------------------------------------------+
| hostname   | The hostname of the server running the Autotest web interface.   |
+------------+------------------------------------------------------------------+


INSTALL_SERVER
--------------

Code to interact with a provisioning system, to make it install clients.

+-----------------+------------------------------------------------------------------------------+
| **Key**         | **Description**                                                              |
+-----------------+------------------------------------------------------------------------------+
| type            | Type of install server we talk to. Default: cobbler                          |
+-----------------+------------------------------------------------------------------------------+
| xmlrpc_url      | RPC server URL for your install server. Example:  http://foo.com/cobbler_api |
+-----------------+------------------------------------------------------------------------------+
| xmlrpc_user     | XMLRPC user, in case the server requires authentication                      |
+-----------------+------------------------------------------------------------------------------+
| xmlrpc_password | XMLRPC password, in case the server requires authentication                  |
+-----------------+------------------------------------------------------------------------------+

SCHEDULER
---------

This section describes the [SCHEDULER] section of the global
configuration.

+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Key**                                  | **Description**                                                                                                                                                        |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| notify_email                             | Email address to receive warning and error messages from the scheduler                                                                                                 |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| notify_email_from                        | Email address from which to send scheduler messages; defaults to the user running the scheduler                                                                        |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| notify_email_statuses                    | When a host in a job reaches one of these statuses, send email to the email_list field of that job. If empty, email will only be sent when the whole job completes.    |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| max_processes_per_drone                  | Maximum number of running Autoserv processes at once on a single server                                                                                                |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| max_jobs_started_per_cycle               | Maximum number of Autoserv processes started within one scheduler cycle                                                                                                |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| max_parse_processes                      | Maximum number of parser processes running at once                                                                                                                     |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| tick_pause_sec                           | The pause (in seconds) between the end of a tick and the beginning of the next tick                                                                                    |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| clean_interval_minutes                   | Time (in minutes) between database sweeps to abort timed-out jobs                                                                                                      |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| synch_job_start_timeout_minutes          | Time (in minutes) after which a synchronous job that has not yet started running will be aborted)                                                                      |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| results_host                             | A host to offload results to via rsync/scp Default: localhost                                                                                                          |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| results_host_installation_directory      | If you installed your results_host in a different location than the standard /usr/local/autotest, this often will be blank                                             |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Distributed execution parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following parameters only need to be changed in a :doc:`Distributed Server Setup <../sysadmin/DistributedServerSetup>`.

+----------------------------------+---------------------------------------------------------------------------------------+
| drones                           | List of hostnames to act as drones (machines that run Autoserv)                       |
+----------------------------------+---------------------------------------------------------------------------------------+
| drone_installation_directory     | Directory in which Autotest is installed on drones, from which Autoserv will be run   |
+----------------------------------+---------------------------------------------------------------------------------------+
| results_host                     | Hostname to copy results to after job completion                                      |
+----------------------------------+---------------------------------------------------------------------------------------+
| max_transfer_processes           | Maximum number of rsync/scp transfers to the results repository at once.              |
+----------------------------------+---------------------------------------------------------------------------------------+

The following are optional parameters that can be used in a :doc:`Distributed Server Setup <../sysadmin/DistributedServerSetup>`.

+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| archive_host                | An additional hostname to check for results files when they cannot be found elsewhere after a user requests logs through the web interface   |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| $hostname_disabled          | If set to 1, the drone $hostname will be disabled -- no new jobs will run, but existed jobs will be seen to completion                       |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| $hostname_max_processes     | Overrides max_processes_per_drone for a particular drone                                                                                     |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+

HOSTS
-----

This section describes the [HOSTS] section of the global configuration.

+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| **Key**               | **Description**                                                                                                   |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| wait_up_processes     | A comma-delimited list of processes that Host.wait_up expects to find one of before it considers the host "up"    |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| default_protection    | Default level of protection to put on new hosts. See :doc:`HostProtections <../frontend/Web/HostProtections>`     |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+

PACKAGES
--------

This section describes the [PACKAGES] section of the global
configuration.

+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Key**                           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| fetch_location                    | `http://myserver.blah.com <http://myserver.blah.com/>`_                                                                                                                                                                                                                                                                                                                                                                                                             |
+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| upload_location                   | /usr/local/autotest/packages                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| serve_packages_from_autoserv      | If set to True, autoserv will act as a last-resort package repository, allowing you to use the packaging system without setting up HTTP repositories. This defaults to True, but in large-scale production setups where you expect to run a large number of simultaneous autoserv processes you may want to disable this as autoserv builds up the package tarballs on-demand and so this is significantly more expensive than serving static packages over HTTP.   |
+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
